ctident
Utility for establishing and maintaining trust between devices within the ProtectToolkit-C environment.
The ctident utility establishes trust between devices. This includes operations performed by the Administrative Token SO to establish trust, as well as operations performed by any user to verify trust relationships.
A device trusts another peer when the device holds the peer's ProtectServer Identity Certificate in its trust store, and, if applicable, that PIC is signed by the same ProtectServer Owner Key as the device's own PIC.
Note
When operating in WLD/HA mode, this utility should only be used to view the configuration. Any changes to the configuration should be made in NORMAL mode. See Operation in WLD Mode and Operation in HA Mode for more information about these operating modes.
Syntax
The following ctident syntax can be used.
Generate a new ProtectServer Owner Key and Self-signed Certificate
ctident gen-owner [-b] [-f] [-l <owner_label>] <CA_HSM>
Generate a new ProtectServer Identity Key and Sign Certificate with POK
ctident gen-key [-b] [-f] -l <owner_label> <CA_HSM> <targets>
Generate a new ProtectServer Identity Key and Self-Signed Certificate
Generate a new ProtectServer Identity Key and Certificate Signing Request
ctident gen-csr [-b] [-f] [-p <filepath>] <targets>
Store a ProtectServer Owner Certificate on the HSM
ctident store-poc [-b] [-f] [-p <filename>] <targets>
Store a Signed ProtectServer Identity Certificate on the HSM
ctident store-pic [-b] [-f] [-p <filename>] <target>
Fetch the ProtectServer Identity Certificate chain from the HSM
Add trust for <peers> to <targets>
ctident trust [-b] [-f] [-o<so_pin>] <targets> <peers>
Remove trust for <peers> from <targets>
List HSM ID keys
ctident list [-b] [-t<types>] [-a] <targets>
Commands
The following ctident commands are available.
When specifying the command, the user need only supply the minimum number of characters to uniquely distinguish the command.
- fetch-certs
-
The fetch-certs command is used to import the certificate key chain from a ProtectServer 3 HSM into a PTK client's trust store. This is required for the client to perform cryptographic operations on the HSM when Secure Messaging is enabled. The cert chain can be imported whether SMS is enabled or not.
- gen-csr
-
The gen-csr command is used to generate a ProtectServer Identity Key pair on the HSM and leave the certificate unsigned as a Certificate Signing Request (CSR). This allows you to sign the CSR with the POK of a ProtectServer 3 HSM CA that is kept offline and separate from your production HSMs, and re-import it as the PIC.
- gen-key
-
The gen-key command is used to generate a ProtectServer Identity Key pair on the HSM and have the ProtectServer Identity Certificate signed by the POK of the HSM serving as Certificate Authority. These PICs are exchanged among the HSMs in your organization to establish trust for Secure Messaging and Token Replication.
- gen-owner
-
The gen-owner command is used to generate a ProtectServer Owner Key and self-signed ProtectServer Owner Certificate on an HSM that you wish to serve as a Certificate Authority for other ProtectServer 3 HSMs in your organization.
- gen-selfsigned
-
The gen-selfsigned command is used to generate a ProtectServer Identity Key and self-signed ProtectServer Identity Certificate. These PICs are exchanged among the HSMs in your organization to establish trust for Secure Messaging and Token Replication.
- list
-
The list key command list is used to list summary information for HSM Identity keys located on the devices specified by the <targets> parameter.
The -t parameter restricts the types of keys listed. By default all HSM Identity keys are listed.
The -a parameter lists all of the non-sensitive attributes for each key/cert.
- remove
-
The remove key command remove is used to remove HSM Identity keys from the devices specified by the <targets> parameter.
The <peers> parameter specifies the peer device keys to remove. If the serial number format is used to identify peers, the peer device need not be available for the command to succeed since peer keys are identified by device serial number.
To complete this command, ctident requires the SO PIN of the administrative token. The -o parameter can be used to supply a default SO PIN. Since multiple devices can be targeted with this command, differing PINs may be required for each device. When a default PIN is not provided or if the current PIN is incorrect, the PIN will be prompted for. The batch mode -b parameter can be used to disable PIN prompting.
- store-pic
-
The store-pic command is used to re-import a ProtectServer Identity Certificate to its own HSM after it has been signed by the POK of an offline HSM CA.
- store-poc
-
The store-poc command is used to store a ProtectServer Owner Certificate on an HSM whose PIC is signed by the corresponding POK.
- trust
-
The trust key command 'trust' is used to add peer HSM Identity public-keys to the devices specified by the <targets> parameter.
The <peers> parameter specifies one or more peer devices to trust.
If a device already has a trusted identity key for a peer, the new key will not be trusted and a warning will be issued, unless the -f parameter is used to force the trust. When forcing trust, the existing peer key is destroyed BEFORE the new key is created to avoid any inconsistencies that could occur with multiple keys.
Before trusting a key a number of checks are performed; the public key is checked to ensure it matches the device private key, and both the public and private key objects are checked to ensure they have been created with appropriate security attributes.
To complete this command, ctident requires the SO PIN of the administrative token. The -o parameter can be used to supply a default SO PIN. Since multiple devices can be targeted with this command, differing PINs may be required for each device. When a default PIN is not provided or if the current PIN is incorrect, the PIN will be prompted for. The batch mode -b parameter can be used to disable PIN prompting.
Options
The following ctident options are available.
- <targets>
-
Specifies a comma-separated list of device numbers. The modifier, sn:<serial> allows device serial numbers to be specified as opposed to device positional numbers. The special value all denotes all devices.
- <peers>
-
Specifies a comma-separated list of peer device numbers. The modifier, sn:<serial> allows device serial numbers to be specified as opposed to device positional numbers. The special value all denotes all devices other than the specific target device on which the command is currently being performed on. The special value local affects the devices own local HSM Identity key-pair and only has effect with the remove command.
- -a, --attributes
-
Output all non-sensitive attributes of a key.
- -b, --batch
-
Batch mode. Do not prompt for anything, including PINs. If the required information was not supplied on the command line ctident will report an error.
- -f, --force
-
Force the command, even if the key already exists.
- -o<pin>, --so-pin=<pin>
-
Specifies the security officer (SO) PIN. Use of this operation is a security risk due to the tools command line being visible in the systems process list.
- -t<types>, --type=<types>
-
Specifies a comma-separated list of key types. The available key types are:
pri - local private keys
pub - local public keys
peer - peer public keys
all - all key types
- -u<pin>
-
Specifies the Administrator PIN. Use of this operation is a security risk due to the tools command line being visible in the systems process list.
Exit Status
The ctident utility will return a zero(0) exit status when successful. A non-zero exit status is returned on an error. Warnings are not treated as errors.
